\chapter{故障排查}
\label{ch:troubleshooting}

当转换或编译出现问题时，可按照本章的步骤快速定位原因。

\section{常见错误类型}

\begin{description}
    \item[找不到 dotnet/roslyn] 重新安装 .NET SDK 8.0，并确认 PATH 中包含 \texttt{/usr/share/dotnet} 或 \filepath{C:\textbackslash Program Files\textbackslash dotnet}
    \item[缺少 C++ 编译器] Linux 安装 \texttt{build-essential}；Windows 打开 ``x64 Native Tools Command Prompt''
    \item[生成代码引用未知类型] 检查生成目录下的 \texttt{*\_stubs.hpp}，补充真实实现或暂时保留桩代码
    \item[命名不符合预期] 在配置文件 \texttt{naming.preserve\_acronyms} 中补充缩写或自定义命名逻辑
    \item[转换失败且日志为空] 执行 \texttt{cpp-orchestrator doctor} 查看依赖是否缺失
\end{description}

\section{日志与调试}

\begin{enumerate}
    \item 使用 `--verbose` 查看详细过程：
    \begin{lstlisting}[style=bash]
cpp-orchestrator convert --project MyGame.csproj --verbose
    \end{lstlisting}
    \item 查看 `~/.cpp-orchestrator/logs/` 中的运行日志
    \item 如果 Roslyn 分析阶段失败，可手动执行 \texttt{dotnet build} 验证 C\# 项目是否能通过编译
\end{enumerate}

\section{编译错误排查}

\subsection{缺少头文件}

多数情况下是遗漏了生成的桩代码头文件，建议在 CMake 中统一加入：

\begin{lstlisting}[style=cpp]
target_include_directories(my_game PUBLIC
    generated-cpp/include
    generated-cpp/include/stubs
)
\end{lstlisting}

\subsection{Acronym 命名不一致}

\textbf{症状：} \code{ID} 被转换为 \code{i\_d}

\textbf{解决：} 在配置文件中声明保留缩写，或在代码中手动修正：

\begin{lstlisting}[style=yaml]
naming:
  preserve_acronyms:
    - ID
    - HTTP
    - SKU
\end{lstlisting}

\subsection{泛型映射不完整}

\textbf{症状：} \code{Dictionary<string>} 只生成单个模板参数

\textbf{解决：} 升级至 Phase 3 之后的版本，已默认修复此问题；如需自定义，可覆盖类型映射。

\section{生成报告}

\begin{lstlisting}[style=bash]
cpp-orchestrator report --format markdown --save-to reports/result.md
\end{lstlisting}

报告中会列出：

\begin{itemize}[leftmargin=*]
    \item 转换成功率
    \item 生成的桩代码列表
    \item 未映射的类型
    \item 需要人工处理的 TODO
\end{itemize}

\section{获取帮助}

\begin{itemize}[leftmargin=*]
    \item 阅读 GitHub Issues 中的典型问答
    \item 在团队内部 wiki 记录自定义映射与桩代码的最佳实践
    \item 使用 `cpp-orchestrator doctor` 自动诊断环境
\end{itemize}

遵循以上步骤，大多数转换与编译问题都能迅速解决。
